8bitfiles.net/archives/archives.tar/archives/compuserve-file-archive/09 Application Software/LOGFIL.DOC

Text File | 2019-04-13 | 15KB | 328 lines

DOCUMENTATION FOR LOGFILE v. 1.0a
(May be freely copied for personal or classroom use; other use requires
author permission)


1.0  Contents of This File

     1.1  Capsule Specifications
     1.2  Minimum equipment required
     1.3  Features
     2.1  First Words
     2.2  Program Overview
     3.0  Getting Started
     3.1  How Many Records?
     3.2  Connect-time Rates
     3.3  Choosing a Filename
     3.4  Use Code Option
     4.0  Adding Records
     5.0  Searching Records
     6.0  Report Generator
     6.1  Printer Support
     7.0  Program Crashes
     7.1  Killing Relative Files
     8.0  Translation to Other Computers
     9.0  Program Alterations

-------------------------------------------------------------------------------

1.1  Capsule Specifications

File size:  720 records
Record length:  254 characters and spaces; present format is 33

Purpose:  To allow user to manage on-line connect times, uses, and
charges, while demonstrating the use of relative files and keylists.

1.2  Minimum equipment required:

     C-64 computer
     1540/1541 disk drive
     Printer optional

1.3  Features:

     Real-time clock display on main menu.
     Search keyfield using all relational operators--plus
range--reduced to alpha-character mnemonics (>= becomes GE).
     Sequential keylist retrieves relative file records, with good
execution speed.
     Keylist 'remembers' certain creation parameters, including date and
time of last update.
     Retrieved data is plugged into pre-defined screen for reading.
     Prepares report with totals; may be either displayed to screen or
printed.
     File status display from main menu of records used/available.
     Extensive input error-checking with entry restrictions.
     Modified 'get' statement with blinking cursor.
     Date & time string manipulation routines.
     Formal exit routine.
     User friendly and virtually transparent operation for
non-programmer.

2.1  First Words

     Several terms are used in this text file with which you should be
familiar.

FIELD:  A record 'blank space' reserved for an item of information.  In
relative files, the 1540/1541 disk operating system (DOS) dictates that
one may have any number of fields provided the total of field lengths and
separating characters or spaces does not exceed 254.

FILE:  The cabinet; not the manila folder.  In Logfile--indeed, in all
relative files--the user establishes a particular 'cabinet' into which he or
she proposes to put individual records.  The filename labels the 'cabinet.'

KEY:  The information stored in a keyfield.

KEYFIELD:  Normally the field into which the most important item of common
identification is entered, as, a customer name.  Ask yourself, 'By what
field would I usually file this record?'

KEYLIST:  A sequential file of all the individual-record keyfields.  In
Logfile, by counting the keyfield sequence, keyfield x corresponds to
relative record x.

RECORD:  Think medical records.  The individual file folder within the file
cabinet.  May be an empty folder, or may contain information.  Our cabinet
may contain up to 720 records.  Beyond that, we'll need another file cabinet.

SEARCH:  In Logfile, using a specified date, or range of dates, plus the
relational operators (=, <>, etc.) to attempt a match to an item in the
keylist.  If the match is successful, the key's position in the sequential
file dictates which corresponding full record is retrieved.


2.2  Program Overview

     Logfile is a relative file and keylist generator, for the C-64 and
1540/1541 disk system, formatted to keep track of on-line connect times and
charges.

     Some months ago, your humble author realized, with shock, that not
every computer owner is interested in programming.  Logfile attempts to shed
some light on what seems to be a neglected area of C-64/1541 literature,
the relative file.  Those few demonstration programs we have seen
appear to relegate their users to remembering record numbers, or to
relying on an exact and equal match with the field in question.  There is
no question that the equipment will support much more sophisticated
operations than these, but no one has taken the time to tell the beginning or
intermediate BASIC programmer how to proceed.

     Besides, BASIC is too slow for database management!  Well, how slow is
'too' slow?  We have the good fortune to own a commercial software package
for the above equipment that will locate and display a record within
three seconds, regardless of file size! Sure, it was written in machine
language, but it also uses keylists.  We submit that the keylist may be an
excellent tool even for a database program in BASIC.  Using a keylist,
Logfile's retrieval speed may even surprise you!


3.0  Getting Started

     If you plan to use Logfile for its pre-formatted purpose, all you need
do is load a working copy by entering the usual direct command, load
"filename",8.  Then run.  We strongly advise you to preserve a master copy,
and work from copies of that.

     After the initial screen, enter the date and time in the formats
specified.  This feature sets the main menu real-time clock and is further
used to date-and-time stamp your reports, as well as to record the date
of keylist updates.  The main menu display is your route to other features
of the program.

3.1  How Many Records?

     Before creating a new file, some thought should be given to the amount
of data you may already have, or will be generating.  For example, if you
merely access CompuServe three times each week to send and read EMAIL, and
want to keep track of your times and charges for a year, you will only need
to 'declare' 156 records for the file.  The major reason for doing things
this way is to increase search speed.  There is no need to declare a
maximum of 720 records in a particular file if you aren't going to use them.

3.2  Connect-time Rates

     Another option is how you wish Logfile to deal with connect-time
rates.  The program will accept and identify a constant rate, as, 06.00 for
$6 per hour.  It will also accept a variable rate that may change as you
build the file.  In the first case, you will not be prompted for the rate in
each record since you are telling the computer the rate will not change.  The
latter option asks for the rate in each record you enter.  The program will
'remember' which option you chose, for your next session with that file.

     A word of caution.  While eliminating all but letters, numbers,
and some punctuation, our modified 'get' statement will accept punctuation
other than the decimal point without error detection, as, the colon for time
strings.  The prompts will always tell you which separator or punctuation to
use.  In the rate case, any punctuation other than a decimal will scramble
later calculations.

3.3  Choosing a Filename

     Since you are already acquainted with a massive information service that
has a fetish for proper filenames, this should be easy.  Most often, the name
of the on-line service is adequate.  Be aware, however, that upper and lower
case are significant.  If you originally enter 'DowJonesNS,' and
later call for 'dowjonesns,' you'll get a 'file not found' error.  Logfile
limits you to a maximum of twelve characters and spaces, to have room for
its own automatic extensions.  The keylist will appear in your disk
directory as 'filename.key.'  The relative file will appear as
'filename.dat.'  This way, the pairs of matched filenames reflect their
purpose, and may co-exist on the same disk.  Do not add these extensions; let
the computer handle that for you.

     Logfile prompts you for a filename before executing any main menu
operation so that, in addition to providing some internal requirements,
you may choose, if you wish, another file.

     After the two files have been created, the only option is returning
to the main menu.  To verify that your files are on the disk, select the file
status display.

3.4  Use Code Option

     Before adding records to your newly-created file, determine which
personal use codes you may want to use.  The program allows three characters
for this.  For example, if you invested 00:17 minutes searching public access
for a discussion of keylists, ultimately downloading this text file,
the code might be 'acc' (for access), or 'dow' (for download).  Similarly,
the cb simulator might appear as 'cbs.'

4.0  Adding Records

     Upon choosing this menu item and calling for the file, the screen will
display a blank record, properly labelled with the filename, and advise
this is 'record nmbr: 1.'  Data entry is simple enough, with the aid of a
blinking cursor and specific prompts.  When one field is properly filled, the
cursor will move to the next.  If you elected to use a constant for the
connect time, this field will be filled by the computer (in light blue
characters on a color monitor or color tv).  The charge calculation is also
automatic, leaving the use code.  When this field is filled, the 'save'
prompt will flash.  You may save the record, delete the record, or quit the
add mode, as you prefer.  Pressing 's' or 'S,' and that letter only will save
the record.  Following a successful save, a new prompt will appear in the
command area under the record format, 'SPC enter next.'  Press the space bar
to display the next blank record, and continue as before.

5.0  Searching Records

     If this program has any real power, it surfaces here.  After calling
for the file, you are given the option of searching by record number (nothing
more than specifying a specific record for retrieval), or searching by our
pre-designated keyfield.  Of the fields in Logfile's present format, only the
date made any sense as a keyfield, although another is possible with a few
modifications.  Similarly, a sort routine was not included since your
records will most likely be entered sequentially by date, in effect
pre-sorting the file.  Selecting the key option displays the available
search relational operators.

     We have elected to use FORTRAN-like mnemonics for these
operators intead of the usual symbols, to add to our user-friendly image.
The object here is to apply a relationship test to the sought-for key.
The proposed key may or may not exist; hence, the search facility.

     For example, suppose that in combating lonliness (for whatever
reason), you remember spending a lot of time on the cb simulator between the
time your cat died, and Christmas day.  The cat expired about mid-November.
Therefore, you need to retrieve all records between 84/11/15 and 84/12/25.
This is a 'range' relationship.  Enter 'rg' or 'RG' (case inversion is never
significant in Logfile commands).

     We have, however, used little error-checking with the standard input
statement.  If the program doesn't recognize your input (say you entered
'rn'), the computer will simply sail through your keylist, searching for an
impossible relationship, to 'end of keylist: no match found'.  Press 's' to
try again.

     The program will prompt for the lowest key in the range, and then the
highest key, and then retrieve the first record in the range, if one
exists, and display it for reading.  Press 'n' to read the next record in
the range.

6.0  Report Generator

     More useful, perhaps, is displaying to the screen, or printing
hardcopy of, the results of your search.  Rather than reading individual
records, this main menu option totals the time and charge columns below
fields of all the records that comprise that particular report.  You may also
prepare a report of all the records in the file, if you wish.  Display or
print 'selected records' on the secondary 'Report Option Menu' searches
for specific records.

6.1  Printer Support

     Logfile assumes a Commodore MPS-801 printer, and sets the printer
secondary address to '7' (cursor down or 'business mode,' upper and lower
case) in line 1545 of the program.  If this is incompatible with your
printer, first determine the proper secondary address for upper and lower case
(try the instruction book), and change the final digit in the program line in
question.  Non-CBM printers may require other measures.

7.0  Program Crashes

     Although Logfile devotes altogether too many blocks to
error-checking and recovery, it is possible to crash the program.  In the
event you get a BASIC error message during a read/write operation, and the
activity light on your disk drive remains steady red, followed by 'ready'
and a blinking cursor, enter in direct mode, 'close5:close2:close1.'  If your
position in the program has involved printer operations, add 'close7' to the
above line.  The red light should go out, and your open files should be
properly closed.

7.1  Killing Relative Files

     If, for any reason, you need to scratch a relative file from your disk
(outside of the Logfile environment), you may not use the save with replace
command '@0:.'  The file must be scratched using 'S0:.'

8.0  Translation to Other Computers

     The limitations of v. 2.0 BASIC have dictated that Logfile use over 14K
to get in all the error checking routines and screen format.  A better
programmer could and should shave this somewhat.  The same programmer could
doubtless accomplish the same ideas on, say, the Mod 100 in 8K or less, given
a disk drive, particularly with a little help from 'on error goto' and 'print
@.'  Did you hear that, Commodore?

     The only major routine in Logfile using machine-specific addresses is the
blinking cursor with 'get,' and a peek to return the physical line number of
the cursor in the report display routine.  CBM-specific syntax, of
course, is used in dealing with the disk drive, although all systems have
an equivalent.  Cosmetics may be ignored.

9.0  Program Alterations

     Serious modifications to Logfile could only be dictated by the condition
of having more time than software money, or a serious interest in
programming.  We readily concede that a number of commercial database programs
will do the job faster and better, with many more features.

     For this reason, we cannot justify uploading a much longer series of text
files telling one what to do and how to do it, without an invitation from a
sig sysop, and some positive feedback from actual users.

     Following our sometimes convoluted logic, however, and multiple passes
through main routines from all four corners, may prove to be more than all
but the most dedicated can endure.

     In the meantime, these detailed instructions are available on disk for
the now traditional copy fee of $3, plus a blank formatted disk, and
self-addressed stamped disk mailer.  Please specify preference of text
format: Speedscript document,
                , or true ASCII.

     If you find bugs, or run into modification snags, use EMAIL.  We'll
send an advance thank you for bug swatting, and a prompt response on other
matters.


Mike Davidson  74116,2507
11845-5th Ave S
Seattle, WA  98168